Skip to main content

Partial Response

Partial Response is a REST API design technique where clients can request only specific fields or properties of a resource rather than the entire resource. This reduces unnecessary data transfer, improving performance and efficiency—especially in cases where resources have many attributes, but the client only needs a few.

Why Partial Response Matters​

  • Performance: Reduces payload size and speeds up response time.
  • Bandwidth Efficiency: Especially important for mobile or limited-bandwidth environments.
  • Flexibility: Gives clients more control over the data they receive.

How Partial Response Works​

Partial response is usually implemented using query parameters like fields. The client specifies which fields they want by passing them in the request:

GET /users/123?fields=id,name,email

The server parses the fields parameter and returns only those fields in the response.

Example of Partial Response​

Imagine a User resource with many fields:

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "address": "123 Main St",
  "phone": "123-456-7890",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-06-01T12:00:00Z"
}

A client only needs id, name, and email.

Request Example:

GET /users/123?fields=id,name,email

How to implement partial response​

  1. Parse Query Parameter: Extract the fields value from the query string.
  2. Validate Fields: Ensure the requested fields exist in the resource model and that the client has permission to access them.
  3. Dynamically Build Response: Use techniques like object filtering or projection in your backend language to send only the specified fields.
app.get("/users/:id", async (req, res) => {
  const fields = req.query.fields ? req.query.fields.split(",") : null;
  const user = await getUserFromDB(req.params.id);

  if (!fields) {
    return res.json(user);
  }

  const partialUser = {};
  fields.forEach((field) => {
    if (user[field] !== undefined) {
      partialUser[field] = user[field];
    }
  });

  res.json(partialUser);
});

Best Practices of partial response​

  • Security: Be careful not to expose sensitive fields accidentally.
  • Field Whitelisting: Only allow fields that are explicitly permitted.
  • Default Behavior: If no fields parameter is provided, return all fields (or a default subset).
  • Tooling Support: Some libraries/frameworks offer automatic support for partial response, especially in GraphQL or with ORM libraries.